home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / gcc / gcc261a.zoo / info / libg++.info-3 < prev    next >
Encoding:
GNU Info File  |  1994-11-07  |  49.1 KB  |  1,398 lines
  1. This is Info file libg++.info, produced by Makeinfo-1.55 from the input
  2. file ./libg++.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Libg++: (libg++).             The g++ class library.
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This file documents the features and implementation of The GNU C++
  9. library
  10.  
  11.    Copyright (C) 1988, 1991, 1992 Free Software Foundation, Inc.
  12.  
  13.    Permission is granted to make and distribute verbatim copies of this
  14. manual provided the copyright notice and this permission notice are
  15. preserved on all copies.
  16.  
  17.    Permission is granted to copy and distribute modified versions of
  18. this manual under the conditions for verbatim copying, provided also
  19. that the section entitled "GNU Library General Public License" is
  20. included exactly as in the original, and provided that the entire
  21. resulting derived work is distributed under the terms of a permission
  22. notice identical to this one.
  23.  
  24.    Permission is granted to copy and distribute translations of this
  25. manual into another language, under the above conditions for modified
  26. versions, except that the section entitled "GNU Library General Public
  27. License" and this permission notice may be included in translations
  28. approved by the Free Software Foundation instead of in the original
  29. English.
  30.  
  32. File: libg++.info,  Node: String,  Next: Integer,  Prev: AllocRing,  Up: Top
  33.  
  34. The String class
  35. ****************
  36.  
  37.    The `String' class is designed to extend GNU C++ to support string
  38. processing capabilities similar to those in languages like Awk.  The
  39. class provides facilities that ought to be convenient and efficient
  40. enough to be useful replacements for `char*' based processing via the C
  41. string library (i.e., `strcpy, strcmp,' etc.) in many applications.
  42. Many details about String representations are described in the
  43. Representation section.
  44.  
  45.    A separate `SubString' class supports substring extraction and
  46. modification operations. This is implemented in a way that user
  47. programs never directly construct or represent substrings, which are
  48. only used indirectly via String operations.
  49.  
  50.    Another separate class, `Regex' is also used indirectly via String
  51. operations in support of regular expression searching, matching, and the
  52. like.  The Regex class is based entirely on the GNU Emacs regex
  53. functions.  *Note Syntax of Regular Expressions: (emacs.info)Regexps,
  54. for a full explanation of regular expression syntax.  (For
  55. implementation details, see the internal documentation in files
  56. `regex.h' and `regex.c'.)
  57.  
  58. Constructors
  59. ============
  60.  
  61.    Strings are initialized and assigned as in the following examples:
  62.  
  63. `String x;  String y = 0; String z = "";'
  64.      Set x, y, and z to the nil string. Note that either 0 or "" may
  65.      always be used to refer to the nil string.
  66.  
  67. `String x = "Hello"; String y("Hello");'
  68.      Set x and y to a copy of the string "Hello".
  69.  
  70. `String x = 'A'; String y('A');'
  71.      Set x and y to the string value "A"
  72.  
  73. `String u = x; String v(x);'
  74.      Set u and v to the same string as String x
  75.  
  76. `String u = x.at(1,4); String v(x.at(1,4));'
  77.      Set u and v to the length 4 substring of x starting at position 1
  78.      (counting indexes from 0).
  79.  
  80. `String x("abc", 2);'
  81.      Sets x to "ab", i.e., the first 2 characters of "abc".
  82.  
  83. `String x = dec(20);'
  84.      Sets x to "20". As here, Strings may be initialized or assigned
  85.      the results of any `char*' function.
  86.  
  87.    There are no directly accessible forms for declaring SubString
  88. variables.
  89.  
  90.    The declaration `Regex r("[a-zA-Z_][a-zA-Z0-9_]*");' creates a
  91. compiled regular expression suitable for use in String operations
  92. described below. (In this case, one that matches any C++ identifier).
  93. The first argument may also be a String.  Be careful in distinguishing
  94. the role of backslashes in quoted GNU C++ char* constants versus those
  95. in Regexes. For example, a Regex that matches either one or more tabs
  96. or all strings beginning with "ba" and ending with any number of
  97. occurrences of "na" could be declared as `Regex r =
  98. "\\(\t+\\)\\|\\(ba\\(na\\)*\\)"' Note that only one backslash is needed
  99. to signify the tab, but two are needed for the parenthesization and
  100. virgule, since the GNU C++ lexical analyzer decodes and strips
  101. backslashes before they are seen by Regex.
  102.  
  103.    There are three additional optional arguments to the Regex
  104. constructor that are less commonly useful:
  105.  
  106. `fast (default 0)'
  107.      `fast' may be set to true (1) if the Regex should be
  108.      "fast-compiled". This causes an additional compilation step that
  109.      is generally worthwhile if the Regex will be used many times.
  110.  
  111. `bufsize (default max(40, length of the string))'
  112.      This is an estimate of the size of the internal compiled
  113.      expression. Set it to a larger value if you know that the
  114.      expression will require a lot of space. If you do not know, do not
  115.      worry: realloc is used if necessary.
  116.  
  117. `transtable (default none == 0)'
  118.      The address of a byte translation table (a char[256]) that
  119.      translates each character before matching.
  120.  
  121.    As a convenience, several Regexes are predefined and usable in any
  122. program. Here are their declarations from `String.h'.
  123.  
  124.      extern Regex RXwhite;      // = "[ \n\t]+"
  125.      extern Regex RXint;        // = "-?[0-9]+"
  126.      extern Regex RXdouble;     // = "-?\\(\\([0-9]+\\.[0-9]*\\)\\|
  127.                                 //    \\([0-9]+\\)\\|
  128.                                 //    \\(\\.[0-9]+\\)\\)
  129.                                 //    \\([eE][---+]?[0-9]+\\)?"
  130.      extern Regex RXalpha;      // = "[A-Za-z]+"
  131.      extern Regex RXlowercase;  // = "[a-z]+"
  132.      extern Regex RXuppercase;  // = "[A-Z]+"
  133.      extern Regex RXalphanum;   // = "[0-9A-Za-z]+"
  134.      extern Regex RXidentifier; // = "[A-Za-z_][A-Za-z0-9_]*"
  135.  
  136. Examples
  137. ========
  138.  
  139.    Most `String' class capabilities are best shown via example.  The
  140. examples below use the following declarations.
  141.  
  142.          String x = "Hello";
  143.          String y = "world";
  144.          String n = "123";
  145.          String z;
  146.          char*  s = ",";
  147.          String lft, mid, rgt;
  148.          Regex  r = "e[a-z]*o";
  149.          Regex  r2("/[a-z]*/");
  150.          char   c;
  151.          int    i, pos, len;
  152.          double f;
  153.          String words[10];
  154.          words[0] = "a";
  155.          words[1] = "b";
  156.          words[2] = "c";
  157.  
  158. Comparing, Searching and Matching
  159. =================================
  160.  
  161.    The usual lexicographic relational operators (`==, !=, <, <=, >, >=')
  162. are defined. A functional form `compare(String, String)' is also
  163. provided, as is `fcompare(String, String)', which compares Strings
  164. without regard for upper vs. lower case.
  165.  
  166.    All other matching and searching operations are based on some form
  167. of the (non-public) `match' and `search' functions.  `match' and
  168. `search' differ in that `match' attempts to match only at the given
  169. starting position, while `search' starts at the position, and then
  170. proceeds left or right looking for a match.  As seen in the following
  171. examples, the second optional `startpos' argument to functions using
  172. `match' and `search' specifies the starting position of the search: If
  173. non-negative, it results in a left-to-right search starting at position
  174. `startpos', and if negative, a right-to-left search starting at
  175. position `x.length() + startpos'. In all cases, the index returned is
  176. that of the beginning of the match, or -1 if there is no match.
  177.  
  178.    Three String functions serve as front ends to `search' and `match'.
  179. `index' performs a search, returning the index, `matches' performs a
  180. match, returning nonzero (actually, the length of the match) on success,
  181. and `contains' is a boolean function performing either a search or
  182. match, depending on whether an index argument is provided:
  183.  
  184. `x.index("lo")'
  185.      returns the zero-based index of the leftmost occurrence of
  186.      substring "lo" (3, in this case).  The argument may be a String,
  187.      SubString, char, char*, or Regex.
  188.  
  189. `x.index("l", 2)'
  190.      returns the index of the first of the leftmost occurrence of "l"
  191.      found starting the search at position x[2], or 2 in this case.
  192.  
  193. `x.index("l", -1)'
  194.      returns the index of the rightmost occurrence of "l", or 3 here.
  195.  
  196. `x.index("l", -3)'
  197.      returns the index of the rightmost occurrence of "l" found by
  198.      starting the search at the 3rd to the last position of x,
  199.      returning 2 in this case.
  200.  
  201. `pos = r.search("leo", 3, len, 0)'
  202.      returns the index of r in the `char*' string of length 3, starting
  203.      at position 0, also placing the  length of the match in reference
  204.      parameter len.
  205.  
  206. `x.contains("He")'
  207.      returns nonzero if the String x contains the substring "He". The
  208.      argument may be a String, SubString, char, char*, or Regex.
  209.  
  210. `x.contains("el", 1)'
  211.      returns nonzero if x contains the substring "el" at position 1.
  212.      As in this example, the second argument to `contains', if present,
  213.      means to match the substring only at that position, and not to
  214.      search elsewhere in the string.
  215.  
  216. `x.contains(RXwhite);'
  217.      returns nonzero if x contains any whitespace (space, tab, or
  218.      newline). Recall that `RXwhite' is a global whitespace Regex.
  219.  
  220. `x.matches("lo", 3)'
  221.      returns nonzero if x starting at position 3 exactly matches "lo",
  222.      with no trailing characters (as it does in this example).
  223.  
  224. `x.matches(r)'
  225.      returns nonzero if String x as a whole matches Regex r.
  226.  
  227. `int f = x.freq("l")'
  228.      returns the number of distinct, nonoverlapping matches to the
  229.      argument (2 in this case).
  230.  
  231. Substring extraction
  232. ====================
  233.  
  234.    Substrings may be extracted via the `at', `before', `through',
  235. `from', and `after' functions.  These behave as either lvalues or
  236. rvalues.
  237.  
  238. `z = x.at(2, 3)'
  239.      sets String z to be equal to the length 3 substring of String x
  240.      starting at zero-based position 2, setting z to "llo" in this
  241.      case. A nil String is returned if the arguments don't make sense.
  242.  
  243. `x.at(2, 2) = "r"'
  244.      Sets what was in positions 2 to 3 of x to "r", setting x to "Hero"
  245.      in this case. As indicated here, SubString assignments may be of
  246.      different lengths.
  247.  
  248. `x.at("He") = "je";'
  249.      x("He") is the substring of x that matches the first occurrence of
  250.      it's argument. The substitution sets x to "jello". If "He" did not
  251.      occur, the substring would be nil, and the assignment would have
  252.      no effect.
  253.  
  254. `x.at("l", -1) = "i";'
  255.      replaces the rightmost occurrence of "l" with "i", setting x to
  256.      "Helio".
  257.  
  258. `z = x.at(r)'
  259.      sets String z to the first match in x of Regex r, or "ello" in this
  260.      case. A nil String is returned if there is no match.
  261.  
  262. `z = x.before("o")'
  263.      sets z to the part of x to the left of the first occurrence of
  264.      "o", or "Hell" in this case. The argument may also be a String,
  265.      SubString, or Regex.  (If there is no match, z is set to "".)
  266.  
  267. `x.before("ll") = "Bri";'
  268.      sets the part of x to the left of "ll" to "Bri", setting x to
  269.      "Brillo".
  270.  
  271. `z = x.before(2)'
  272.      sets z to the part of x to the left of x[2], or "He" in this case.
  273.  
  274. `z = x.after("Hel")'
  275.      sets z to the part of x to the right of "Hel", or "lo" in this
  276.      case.
  277.  
  278. `z = x.through("el")'
  279.      sets z to the part of x up and including "el", or "Hel" in this
  280.      case.
  281.  
  282. `z = x.from("el")'
  283.      sets z to the part of x from "el" to the end, or "ello" in this
  284.      case.
  285.  
  286. `x.after("Hel") = "p";'
  287.      sets x to "Help";
  288.  
  289. `z = x.after(3)'
  290.      sets z to the part of x to the right of x[3] or "o" in this case.
  291.  
  292. `z = "  ab c"; z = z.after(RXwhite)'
  293.      sets z to the part of its old string to the right of the first
  294.      group of whitespace, setting z to "ab c"; Use gsub(below) to strip
  295.      out multiple occurrences of whitespace or any pattern.
  296.  
  297. `x[0] = 'J';'
  298.      sets the first element of x to 'J'. x[i] returns a reference to
  299.      the ith element of x, or triggers an error if i is out of range.
  300.  
  301. `common_prefix(x, "Help")'
  302.      returns the String containing the common prefix of the two Strings
  303.      or "Hel" in this case.
  304.  
  305. `common_suffix(x, "to")'
  306.      returns the String containing the common suffix of the two Strings
  307.      or "o" in this case.
  308.  
  309. Concatenation
  310. =============
  311.  
  312. `z = x + s + ' ' + y.at("w") + y.after("w") + ".";'
  313.      sets z to "Hello, world."
  314.  
  315. `x += y;'
  316.      sets x to "Helloworld"
  317.  
  318. `cat(x, y, z)'
  319.      A faster way to say z = x + y.
  320.  
  321. `cat(z, y, x, x)'
  322.      Double concatenation; A faster way to say x = z + y + x.
  323.  
  324. `y.prepend(x);'
  325.      A faster way to say y = x + y.
  326.  
  327. `z = replicate(x, 3);'
  328.      sets z to "HelloHelloHello".
  329.  
  330. `z = join(words, 3, "/")'
  331.      sets z to the concatenation of the first 3 Strings in String array
  332.      words, each separated by "/", setting z to "a/b/c" in this case.
  333.      The last argument may be "" or 0, indicating no separation.
  334.  
  335. Other manipulations
  336. ===================
  337.  
  338. `z = "this string has five words"; i = split(z, words, 10, RXwhite);'
  339.      sets up to 10 elements of String array words to the parts of z
  340.      separated by whitespace, and returns the number of parts actually
  341.      encountered (5 in this case). Here, words[0] = "this", words[1] =
  342.      "string", etc.  The last argument may be any of the usual.  If
  343.      there is no match, all of z ends up in words[0]. The words array
  344.      is *not* dynamically created by split.
  345.  
  346. `int nmatches x.gsub("l","ll")'
  347.      substitutes all original occurrences of "l" with "ll", setting x
  348.      to "Hellllo". The first argument may be any of the usual,
  349.      including Regex.  If the second argument is "" or 0, all
  350.      occurrences are deleted. gsub returns the number of matches that
  351.      were replaced.
  352.  
  353. `z = x + y;  z.del("loworl");'
  354.      deletes the leftmost occurrence of "loworl" in z, setting z to
  355.      "Held".
  356.  
  357. `z = reverse(x)'
  358.      sets z to the reverse of x, or "olleH".
  359.  
  360. `z = upcase(x)'
  361.      sets z to x, with all letters set to uppercase, setting z to
  362.      "HELLO"
  363.  
  364. `z = downcase(x)'
  365.      sets z to x, with all letters set to lowercase, setting z to
  366.      "hello"
  367.  
  368. `z = capitalize(x)'
  369.      sets z to x, with the first letter of each word set to uppercase,
  370.      and all others to lowercase, setting z to "Hello"
  371.  
  372. `x.reverse(), x.upcase(), x.downcase(), x.capitalize()'
  373.      in-place, self-modifying versions of the above.
  374.  
  375. Reading, Writing and Conversion
  376. ===============================
  377.  
  378. `cout << x'
  379.      writes out x.
  380.  
  381. `cout << x.at(2, 3)'
  382.      writes out the substring "llo".
  383.  
  384. `cin >> x'
  385.      reads a whitespace-bounded string into x.
  386.  
  387. `x.length()'
  388.      returns the length of String x (5, in this case).
  389.  
  390. `s = (const char*)x'
  391.      can be used to extract the `char*' char array. This coercion is
  392.      useful for sending a String as an argument to any function
  393.      expecting a `const char*' argument (like `atoi', and
  394.      `File::open'). This operator must be used with care, since the
  395.      conversion returns a pointer to `String' internals without copying
  396.      the characters: The resulting `(char*)' is only valid until the
  397.      next String operation,  and you must not modify it.  (The
  398.      conversion is defined to return a const value so that GNU C++ will
  399.      produce warning and/or error messages if changes are attempted.)
  400.  
  402. File: libg++.info,  Node: Integer,  Next: Rational,  Prev: String,  Up: Top
  403.  
  404. The Integer class.
  405. ******************
  406.  
  407.    The `Integer' class provides multiple precision integer arithmetic
  408. facilities. Some representation details are discussed in the
  409. Representation section.
  410.  
  411.    `Integers' may be up to `b * ((1 << b) - 1)' bits long, where `b' is
  412. the number of bits per short (typically 1048560 bits when `b = 16').
  413. The implementation assumes that a `long' is at least twice as long as a
  414. `short'. This assumption hides beneath almost all primitive operations,
  415. and would be very difficult to change. It also relies on correct
  416. behavior of *unsigned* arithmetic operations.
  417.  
  418.    Some of the arithmetic algorithms are very loosely based on those
  419. provided in the MIT Scheme `bignum.c' release, which is Copyright (c)
  420. 1987 Massachusetts Institute of Technology. Their use here falls within
  421. the provisions described in the Scheme release.
  422.  
  423.    Integers may be constructed in the following ways:
  424. `Integer x;'
  425.      Declares an uninitialized Integer.
  426.  
  427. `Integer x = 2; Integer y(2);'
  428.      Set x and y to the Integer value 2;
  429.  
  430. `Integer u(x); Integer v = x;'
  431.      Set u and v to the same value as x.
  432.  
  433.  - Method: long Integer::as_long() const
  434.      Used to coerce an `Integer' back into longs via the `long'
  435.      coercion operator. If the Integer cannot fit into a long, this
  436.      returns MINLONG or MAXLONG (depending on the sign) where MINLONG
  437.      is the most negative, and MAXLONG is the most positive
  438.      representable long.
  439.  
  440.  - Method: int Integer::fits_in_long() const
  441.      Returns true iff the `Integer' is `< MAXLONG' and `> MINLONG'.
  442.  
  443.  - Method: double Integer::as_double() const
  444.      Coerce the `Integer' to a `double', with potential loss of
  445.      precision.  `+/-HUGE' is returned if the Integer cannot fit into a
  446.      double.
  447.  
  448.  - Method: int Integer::fits_in_double() const
  449.      Returns true iff the `Integer' can fit into a double.
  450.  
  451.    All of the usual arithmetic operators are provided (`+, -, *, /, %,
  452. +=, ++, -=, --, *=, /=, %=, ==, !=, <, <=, >, >=').  All operators
  453. support special versions for mixed arguments of Integers and regular
  454. C++ longs in order to avoid useless coercions, as well as to allow
  455. automatic promotion of shorts and ints to longs, so that they may be
  456. applied without additional Integer coercion operators.  The only
  457. operators that behave differently than the corresponding int or long
  458. operators are `++' and `--'.  Because C++ does not distinguish prefix
  459. from postfix application, these are declared as `void' operators, so
  460. that no confusion can result from applying them as postfix.  Thus, for
  461. Integers x and y, ` ++x; y = x; ' is correct, but ` y = ++x; ' and ` y
  462. = x++; ' are not.
  463.  
  464.    Bitwise operators (`~', `&', `|', `^', `<<', `>>', `&=', `|=', `^=',
  465. `<<=', `>>=') are also provided.  However, these operate on
  466. sign-magnitude, rather than two's complement representations. The sign
  467. of the result is arbitrarily taken as the sign of the first argument.
  468. For example, `Integer(-3) & Integer(5)' returns `Integer(-1)', not -3,
  469. as it would using two's complement. Also, `~', the complement operator,
  470. complements only those bits needed for the representation.  Bit
  471. operators are also provided in the BitSet and BitString classes. One of
  472. these classes should be used instead of Integers when the results of
  473. bit manipulations are not interpreted numerically.
  474.  
  475.    The following utility functions are also provided. (All arguments
  476. are Integers unless otherwise noted).
  477.  
  478.  - Function: void divide(const Integer& X, const Integer& Y, Integer&
  479.           Q, Integer& R)
  480.      Sets Q to the quotient and R to the remainder of X and Y.  (Q and
  481.      R are returned by reference).
  482.  
  483.  - Function: Integer pow(const Integer& X, const Integer& P)
  484.      Returns X raised to the power P.
  485.  
  486.  - Function: Integer Ipow(long X, long P)
  487.      Returns X raised to the power P.
  488.  
  489.  - Function: Integer gcd(const Integer& X, const Integer& P)
  490.      Returns the greatest common divisor of X and Y.
  491.  
  492.  - Function: Integer lcm(const Integer& X, const Integer& P)
  493.      Returns the least common multiple of X and Y.
  494.  
  495.  - Function: Integer abs(const Integer& X
  496.      Returns the absolute value of X.
  497.  
  498.  - Method: void Integer::negate()
  499.      Negates `this' in place.
  500.  
  501. `Integer sqr(x)'
  502.      returns x * x;
  503.  
  504. `Integer sqrt(x)'
  505.      returns the floor of the  square root of x.
  506.  
  507. `long lg(x);'
  508.      returns the floor of the base 2 logarithm of abs(x)
  509.  
  510. `int sign(x)'
  511.      returns -1 if x is negative, 0 if zero, else +1.  Using `if
  512.      (sign(x) == 0)' is a generally faster method of testing for zero
  513.      than using relational operators.
  514.  
  515. `int even(x)'
  516.      returns true if x is an even number
  517.  
  518. `int odd(x)'
  519.      returns true if x is an odd number.
  520.  
  521. `void setbit(Integer& x, long b)'
  522.      sets the b'th bit (counting right-to-left from zero) of x to 1.
  523.  
  524. `void clearbit(Integer& x, long b)'
  525.      sets the b'th bit of x to 0.
  526.  
  527. `int testbit(Integer x, long b)'
  528.      returns true if the b'th bit of x is 1.
  529.  
  530. `Integer atoI(char* asciinumber, int base = 10);'
  531.      converts the base base char* string into its Integer form.
  532.  
  533. `void Integer::printon(ostream& s, int base = 10, int width = 0);'
  534.      prints the ascii string value of `(*this)' as a base `base'
  535.      number, in field width at least `width'.
  536.  
  537. `ostream << x;'
  538.      prints x in base ten format.
  539.  
  540. `istream >> x;'
  541.      reads x as a base ten number.
  542.  
  543. `int compare(Integer x, Integer y)'
  544.      returns a negative number if x<y, zero if x==y, or positive if x>y.
  545.  
  546. `int ucompare(Integer x, Integer y)'
  547.      like compare, but performs unsigned comparison.
  548.  
  549. `add(x, y, z)'
  550.      A faster way to say z = x + y.
  551.  
  552. `sub(x, y, z)'
  553.      A faster way to say z = x - y.
  554.  
  555. `mul(x, y, z)'
  556.      A faster way to say z = x * y.
  557.  
  558. `div(x, y, z)'
  559.      A faster way to say z = x / y.
  560.  
  561. `mod(x, y, z)'
  562.      A faster way to say z = x % y.
  563.  
  564. `and(x, y, z)'
  565.      A faster way to say z = x & y.
  566.  
  567. `or(x, y, z)'
  568.      A faster way to say z = x | y.
  569.  
  570. `xor(x, y, z)'
  571.      A faster way to say z = x ^ y.
  572.  
  573. `lshift(x, y, z)'
  574.      A faster way to say z = x << y.
  575.  
  576. `rshift(x, y, z)'
  577.      A faster way to say z = x >> y.
  578.  
  579. `pow(x, y, z)'
  580.      A faster way to say z = pow(x, y).
  581.  
  582. `complement(x, z)'
  583.      A faster way to say z = ~x.
  584.  
  585. `negate(x, z)'
  586.      A faster way to say z = -x.
  587.  
  589. File: libg++.info,  Node: Rational,  Next: Complex,  Prev: Integer,  Up: Top
  590.  
  591. The Rational Class
  592. ******************
  593.  
  594.    Class `Rational' provides multiple precision rational number
  595. arithmetic. All rationals are maintained in simplest form (i.e., with
  596. the numerator and denominator relatively prime, and with the
  597. denominator strictly positive).  Rational arithmetic and relational
  598. operators are provided (`+, -, *, /, +=, -=, *=, /=, ==, !=, <, <=, >,
  599. >=').  Operations resulting in a rational number with zero denominator
  600. trigger an exception.
  601.  
  602.    Rationals may be constructed and used in the following ways:
  603.  
  604. `Rational x;'
  605.      Declares an uninitialized Rational.
  606.  
  607. `Rational x = 2; Rational y(2);'
  608.      Set x and y to the Rational value 2/1;
  609.  
  610. `Rational x(2, 3);'
  611.      Sets x to the Rational value 2/3;
  612.  
  613. `Rational x = 1.2;'
  614.      Sets x to a Rational value close to 1.2. Any double precision value
  615.      may be used to construct a Rational. The Rational will possess
  616.      exactly as much precision as the double. Double values that do not
  617.      have precise floating point equivalents (like 1.2) produce
  618.      similarly imprecise rational values.
  619.  
  620. `Rational x(Integer(123), Integer(4567));'
  621.      Sets x to the Rational value 123/4567.
  622.  
  623. `Rational u(x); Rational v = x;'
  624.      Set u and v to the same value as x.
  625.  
  626. `double(Rational x)'
  627.      A Rational may be coerced to a double with potential loss of
  628.      precision. +/-HUGE is returned if it will not fit.
  629.  
  630. `Rational abs(x)'
  631.      returns the absolute value of x.
  632.  
  633. `void x.negate()'
  634.      negates x.
  635.  
  636. `void x.invert()'
  637.      sets x to 1/x.
  638.  
  639. `int sign(x)'
  640.      returns 0 if x is zero, 1 if positive, and -1 if negative.
  641.  
  642. `Rational sqr(x)'
  643.      returns x * x.
  644.  
  645. `Rational pow(x, Integer y)'
  646.      returns x to the y power.
  647.  
  648. `Integer x.numerator()'
  649.      returns the numerator.
  650.  
  651. `Integer x.denominator()'
  652.      returns the denominator.
  653.  
  654. `Integer floor(x)'
  655.      returns the greatest Integer less than x.
  656.  
  657. `Integer ceil(x)'
  658.      returns the least Integer greater than x.
  659.  
  660. `Integer trunc(x)'
  661.      returns the Integer part of x.
  662.  
  663. `Integer round(x)'
  664.      returns the nearest Integer to x.
  665.  
  666. `int compare(x, y)'
  667.      returns a negative, zero, or positive number signifying whether x
  668.      is less than, equal to, or greater than y.
  669.  
  670. `ostream << x;'
  671.      prints x in the form num/den, or just num if the denominator is
  672.      one.
  673.  
  674. `istream >> x;'
  675.      reads x in the form num/den, or just num in which case the
  676.      denominator is set to one.
  677.  
  678. `add(x, y, z)'
  679.      A faster way to say z = x + y.
  680.  
  681. `sub(x, y, z)'
  682.      A faster way to say z = x - y.
  683.  
  684. `mul(x, y, z)'
  685.      A faster way to say z = x * y.
  686.  
  687. `div(x, y, z)'
  688.      A faster way to say z = x / y.
  689.  
  690. `pow(x, y, z)'
  691.      A faster way to say z = pow(x, y).
  692.  
  693. `negate(x, z)'
  694.      A faster way to say z = -x.
  695.  
  697. File: libg++.info,  Node: Complex,  Next: Fix,  Prev: Rational,  Up: Top
  698.  
  699. The Complex class.
  700. ******************
  701.  
  702.    Class `Complex' is implemented in a way similar to that described by
  703. Stroustrup. In keeping with libg++ conventions, the class is named
  704. `Complex', not `complex'.  Complex arithmetic and relational operators
  705. are provided (`+, -, *, /, +=, -=, *=, /=, ==, !=').  Attempted
  706. division by (0, 0) triggers an exception.
  707.  
  708.    Complex numbers may be constructed and used in the following ways:
  709.  
  710. `Complex x;'
  711.      Declares an uninitialized Complex.
  712.  
  713. `Complex x = 2; Complex y(2.0);'
  714.      Set x and y to the Complex value (2.0, 0.0);
  715.  
  716. `Complex x(2, 3);'
  717.      Sets x to the Complex value (2, 3);
  718.  
  719. `Complex u(x); Complex v = x;'
  720.      Set u and v to the same value as x.
  721.  
  722. `double real(Complex& x);'
  723.      returns the real part of x.
  724.  
  725. `double imag(Complex& x);'
  726.      returns the imaginary part of x.
  727.  
  728. `double abs(Complex& x);'
  729.      returns the magnitude of x.
  730.  
  731. `double norm(Complex& x);'
  732.      returns the square of the magnitude of x.
  733.  
  734. `double arg(Complex& x);'
  735.      returns the argument (amplitude) of x.
  736.  
  737. `Complex polar(double r, double t = 0.0);'
  738.      returns a Complex with abs of r and arg of t.
  739.  
  740. `Complex conj(Complex& x);'
  741.      returns the complex conjugate of x.
  742.  
  743. `Complex cos(Complex& x);'
  744.      returns the complex cosine of x.
  745.  
  746. `Complex sin(Complex& x);'
  747.      returns the complex sine of x.
  748.  
  749. `Complex cosh(Complex& x);'
  750.      returns the complex hyperbolic cosine of x.
  751.  
  752. `Complex sinh(Complex& x);'
  753.      returns the complex hyperbolic sine of x.
  754.  
  755. `Complex exp(Complex& x);'
  756.      returns the exponential of x.
  757.  
  758. `Complex log(Complex& x);'
  759.      returns the natural log of x.
  760.  
  761. `Complex pow(Complex& x, long p);'
  762.      returns x raised to the p power.
  763.  
  764. `Complex pow(Complex& x, Complex& p);'
  765.      returns x raised to the p power.
  766.  
  767. `Complex sqrt(Complex& x);'
  768.      returns the square root of x.
  769.  
  770. `ostream << x;'
  771.      prints x in the form (re, im).
  772.  
  773. `istream >> x;'
  774.      reads x in the form (re, im), or just (re) or re in which case the
  775.      imaginary part is set to zero.
  776.  
  778. File: libg++.info,  Node: Fix,  Next: Bit,  Prev: Complex,  Up: Top
  779.  
  780. Fixed precision numbers
  781. ***********************
  782.  
  783.    Classes `Fix16', `Fix24', `Fix32', and `Fix48' support operations on
  784. 16, 24, 32, or 48 bit quantities that are considered as real numbers in
  785. the range [-1, +1).  Such numbers are often encountered in digital
  786. signal processing applications. The classes may be be used in isolation
  787. or together.  Class `Fix32' operations are entirely self-contained.
  788. Class `Fix16' operations are self-contained except that the
  789. multiplication operation `Fix16 * Fix16' returns a `Fix32'. `Fix24' and
  790. `Fix48' are similarly related.
  791.  
  792.    The standard arithmetic and relational operations are supported
  793. (`=', `+', `-', `*', `/', `<<', `>>', `+=', `-=', `*=', `/=', `<<=',
  794. `>>=', `==', `!=', `<', `<=', `>', `>=').  All operations include
  795. provisions for special handling in cases where the result exceeds +/-
  796. 1.0. There are two cases that may be handled separately: "overflow"
  797. where the results of addition and subtraction operations go out of
  798. range, and all other "range errors" in which resulting values go
  799. off-scale (as with division operations, and assignment or
  800. initialization with off-scale values). In signal processing
  801. applications, it is often useful to handle these two cases differently.
  802. Handlers take one argument, a reference to the integer mantissa of the
  803. offending value, which may then be manipulated.  In cases of overflow,
  804. this value is the result of the (integer) arithmetic computation on the
  805. mantissa; in others it is a fully saturated (i.e., most positive or
  806. most negative) value. Handling may be reset to any of several provided
  807. functions or any other user-defined function via `set_overflow_handler'
  808. and `set_range_error_handler'. The provided functions for `Fix16' are
  809. as follows (corresponding functions are also supported for the others).
  810.  
  811. `Fix16_overflow_saturate'
  812.      The default overflow handler. Results are "saturated": positive
  813.      results are set to the largest representable value (binary
  814.      0.111111...), and negative values to -1.0.
  815.  
  816. `Fix16_ignore'
  817.      Performs no action. For overflow, this will allow addition and
  818.      subtraction operations to "wrap around" in the same manner as
  819.      integer arithmetic, and for saturation, will leave values
  820.      saturated.
  821.  
  822. `Fix16_overflow_warning_saturate'
  823.      Prints a warning message on standard error, then saturates the
  824.      results.
  825.  
  826. `Fix16_warning'
  827.      The default range_error handler. Prints a warning message on
  828.      standard error; otherwise leaving the argument unmodified.
  829.  
  830. `Fix16_abort'
  831.      prints an error message on standard error, then aborts execution.
  832.  
  833.    In addition to arithmetic operations, the following are provided:
  834.  
  835. `Fix16 a = 0.5;'
  836.      Constructs fixed precision objects from double precision values.
  837.      Attempting to initialize to a value outside the range invokes the
  838.      range_error handler, except, as a convenience, initialization to
  839.      1.0 sets the variable to the most positive representable value
  840.      (binary 0.1111111...) without invoking the handler.
  841.  
  842. `short& mantissa(a); long& mantissa(b);'
  843.      return a * pow(2, 15) or b * pow(2, 31) as an integer. These are
  844.      returned by reference, to enable "manual" data manipulation.
  845.  
  846. `double value(a); double value(b);'
  847.      return a or b as floating point numbers.
  848.  
  850. File: libg++.info,  Node: Bit,  Next: Random,  Prev: Fix,  Up: Top
  851.  
  852. Classes for Bit manipulation
  853. ****************************
  854.  
  855.    libg++ provides several different classes supporting the use and
  856. manipulation of collections of bits in different ways.
  857.  
  858.    * Class `Integer' provides "integer" semantics. It supports
  859.      manipulation of bits in ways that are often useful when treating
  860.      bit arrays as numerical (integer) quantities.  This class is
  861.      described elsewhere.
  862.  
  863.    * Class `BitSet' provides "set" semantics. It supports operations
  864.      useful when treating collections of bits as representing
  865.      potentially infinite sets of integers.
  866.  
  867.    * Class `BitSet32' supports fixed-length BitSets holding exactly 32
  868.      bits.
  869.  
  870.    * Class `BitSet256' supports fixed-length BitSets holding exactly
  871.      256 bits.
  872.  
  873.    * Class `BitString' provides "string" (or "vector") semantics.  It
  874.      supports operations useful when treating collections of bits as
  875.      strings of zeros and ones.
  876.  
  877.    These classes also differ in the following ways:
  878.  
  879.    * BitSets are logically infinite. Their space is dynamically altered
  880.      to adjust to the smallest number of consecutive bits actually
  881.      required to represent the sets. Integers also have this property.
  882.      BitStrings are logically finite, but their sizes are internally
  883.      dynamically managed to maintain proper length. This means that,
  884.      for example, BitStrings are concatenatable while BitSets and
  885.      Integers are not.
  886.  
  887.    * BitSet32 and BitSet256 have precisely the same properties as
  888.      BitSets, except that they use constant fixed length bit vectors.
  889.  
  890.    * While all classes support basic unary and binary operations `~, &,
  891.      |, ^, -', the semantics differ. BitSets perform bit operations that
  892.      precisely mirror those for infinite sets. For example,
  893.      complementing an empty BitSet returns one representing an infinite
  894.      number of set bits.  Operations on BitStrings and Integers operate
  895.      only on those bits actually present in the representation.  For
  896.      BitStrings and Integers, the the `&' operation returns a BitString
  897.      with a length equal to the minimum length of the operands, and `|,
  898.      ^' return one with length of the maximum.
  899.  
  900.    * Only BitStrings support substring extraction and bit pattern
  901.      matching.
  902.  
  903. BitSet
  904. ======
  905.  
  906.    BitSets are objects that contain logically infinite sets of
  907. nonnegative integers.  Representational details are discussed in the
  908. Representation chapter. Because they are logically infinite, all
  909. BitSets possess a trailing, infinitely replicated 0 or 1 bit, called
  910. the "virtual bit", and indicated via 0* or 1*.
  911.  
  912.    BitSet32 and BitSet256 have they same properties, except they are of
  913. fixed length, and thus have no virtual bit.
  914.  
  915.    BitSets may be constructed as follows:
  916.  
  917. `BitSet a;'
  918.      declares an empty BitSet.
  919.  
  920. `BitSet a = atoBitSet("001000");'
  921.      sets a to the BitSet 0010*, reading left-to-right. The "0*"
  922.      indicates that the set ends with an infinite number of zero
  923.      (clear) bits.
  924.  
  925. `BitSet a = atoBitSet("00101*");'
  926.      sets a to the BitSet 00101*, where "1*" means that the set ends
  927.      with an infinite number of one (set) bits.
  928.  
  929. `BitSet a = longtoBitSet((long)23);'
  930.      sets a to the BitSet 111010*, the binary representation of decimal
  931.      23.
  932.  
  933. `BitSet a = utoBitSet((unsigned)23);'
  934.      sets a to the BitSet 111010*, the binary representation of decimal
  935.      23.
  936.  
  937.    The following functions and operators are provided (Assume the
  938. declaration of BitSets a = 0011010*, b = 101101*, throughout, as
  939. examples).
  940.  
  941. `~a'
  942.      returns the complement of a, or 1100101* in this case.
  943.  
  944. `a.complement()'
  945.      sets a to ~a.
  946.  
  947. `a & b; a &= b;'
  948.      returns a intersected with b, or 0011010*.
  949.  
  950. `a | b; a |= b;'
  951.      returns a unioned with b, or 1011111*.
  952.  
  953. `a - b; a -= b;'
  954.      returns the set difference of a and b, or 000010*.
  955.  
  956. `a ^ b; a ^= b;'
  957.      returns the symmetric difference of a and b, or 1000101*.
  958.  
  959. `a.empty()'
  960.      returns true if a is an empty set.
  961.  
  962. `a == b;'
  963.      returns true if a and b contain the same set.
  964.  
  965. `a <= b;'
  966.      returns true if a is a subset of b.
  967.  
  968. `a < b;'
  969.      returns true if a is a proper subset of b;
  970.  
  971. `a != b; a >= b; a > b;'
  972.      are the converses of the above.
  973.  
  974. `a.set(7)'
  975.      sets the 7th (counting from 0) bit of a, setting a to 001111010*
  976.  
  977. `a.clear(2)'
  978.      clears the 2nd bit bit of a, setting a to 00011110*
  979.  
  980. `a.clear()'
  981.      clears all bits of a;
  982.  
  983. `a.set()'
  984.      sets all bits of a;
  985.  
  986. `a.invert(0)'
  987.      complements the 0th bit of a, setting a to 10011110*
  988.  
  989. `a.set(0,1)'
  990.      sets the 0th through 1st bits of a, setting a to 110111110* The
  991.      two-argument versions of clear and invert are similar.
  992.  
  993. `a.test(3)'
  994.      returns true if the 3rd bit of a is set.
  995.  
  996. `a.test(3, 5)'
  997.      returns true if any of bits 3 through 5 are set.
  998.  
  999. `int i = a[3]; a[3] = 0;'
  1000.      The subscript operator allows bits to be inspected and changed via
  1001.      standard subscript semantics, using a friend class BitSetBit.  The
  1002.      use of the subscript operator a[i] rather than a.test(i) requires
  1003.      somewhat greater overhead.
  1004.  
  1005. `a.first(1) or a.first()'
  1006.      returns the index of the first set bit of a (2 in this case), or
  1007.      -1 if no bits are set.
  1008.  
  1009. `a.first(0)'
  1010.      returns the index of the first clear bit of a (0 in this case), or
  1011.      -1 if no bits are clear.
  1012.  
  1013. `a.next(2, 1) or a.next(2)'
  1014.      returns the index of the next bit after position 2 that is set (3
  1015.      in this case) or -1. `first' and `next' may be used as iterators,
  1016.      as in `for (int i = a.first(); i >= 0; i = a.next(i))...'.
  1017.  
  1018. `a.last(1)'
  1019.      returns the index of the rightmost set bit, or -1 if there or no
  1020.      set bits or all set bits.
  1021.  
  1022. `a.prev(3, 0)'
  1023.      returns the index of the previous clear bit before position 3.
  1024.  
  1025. `a.count(1)'
  1026.      returns the number of set bits in a, or -1 if there are an
  1027.      infinite number.
  1028.  
  1029. `a.virtual_bit()'
  1030.      returns the trailing (infinitely replicated) bit of a.
  1031.  
  1032. `a = atoBitSet("ababX", 'a', 'b', 'X');'
  1033.      converts the char* string into a bitset, with 'a' denoting false,
  1034.      'b' denoting true, and 'X' denoting infinite replication.
  1035.  
  1036. `a.printon(cout, '-', '.', 0)'
  1037.      prints `a' to `cout' represented with `'-'' for falses, `'.'' for
  1038.      trues, and no replication marker.
  1039.  
  1040. `cout << a'
  1041.      prints `a' to `cout' (representing lases by `'f'', trues by `'t'',
  1042.      and using `'*'' as the replication marker).
  1043.  
  1044. `diff(x, y, z)'
  1045.      A faster way to say z = x - y.
  1046.  
  1047. `and(x, y, z)'
  1048.      A faster way to say z = x & y.
  1049.  
  1050. `or(x, y, z)'
  1051.      A faster way to say z = x | y.
  1052.  
  1053. `xor(x, y, z)'
  1054.      A faster way to say z = x ^ y.
  1055.  
  1056. `complement(x, z)'
  1057.      A faster way to say z = ~x.
  1058.  
  1059. BitString
  1060. =========
  1061.  
  1062.    BitStrings are objects that contain arbitrary-length strings of
  1063. zeroes and ones. BitStrings possess some features that make them behave
  1064. like sets, and others that behave as strings. They are useful in
  1065. applications (such as signature-based algorithms) where both
  1066. capabilities are needed.  Representational details are discussed in the
  1067. Representation chapter.  Most capabilities are exact analogs of those
  1068. supported in the BitSet and String classes.  A BitSubString is used
  1069. with substring operations along the same lines as the String SubString
  1070. class.  A BitPattern class is used for masked bit pattern searching.
  1071.  
  1072.    Only a default constructor is supported.  The declaration `BitString
  1073. a;' initializes a to be an empty BitString.  BitStrings may often be
  1074. initialized via `atoBitString' and `longtoBitString'.
  1075.  
  1076.    Set operations (` ~, complement, &, &=, |, |=, -, ^, ^=') behave
  1077. just as the BitSet versions, except that there is no "virtual bit":
  1078. complementing complements only those bits in the BitString, and all
  1079. binary operations across unequal length BitStrings assume a virtual bit
  1080. of zero. The `&' operation returns a BitString with a length equal to
  1081. the minimum length of the operands, and `|, ^' return one with length
  1082. of the maximum.
  1083.  
  1084.    Set-based relational operations (`==, !=, <=, <, >=, >') follow the
  1085. same rules. A string-like lexicographic comparison function,
  1086. `lcompare', tests the lexicographic relation between two BitStrings.
  1087. For example, lcompare(1100, 0101) returns 1, since the first BitString
  1088. starts with 1 and the second with 0.
  1089.  
  1090.    Individual bit setting, testing, and iterator operations (`set,
  1091. clear, invert, test, first, next, last, prev') are also like those for
  1092. BitSets. BitStrings are automatically expanded when setting bits at
  1093. positions greater than their current length.
  1094.  
  1095.    The string-based capabilities are just as those for class String.
  1096. BitStrings may be concatenated (`+, +='), searched (`index, contains,
  1097. matches'), and extracted into BitSubStrings (`before, at, after') which
  1098. may be assigned and otherwise manipulated. Other string-based utility
  1099. functions (`reverse, common_prefix, common_suffix') are also provided.
  1100. These have the same capabilities and descriptions as those for Strings.
  1101.  
  1102.    String-oriented operations can also be performed with a mask via
  1103. class BitPattern. BitPatterns consist of two BitStrings, a pattern and
  1104. a mask. On searching and matching, bits in the pattern that correspond
  1105. to 0 bits in the mask are ignored. (The mask may be shorter than the
  1106. pattern, in which case trailing mask bits are assumed to be 0). The
  1107. pattern and mask are both public variables, and may be individually
  1108. subjected to other bit operations.
  1109.  
  1110.    Converting to char* and printing (`(atoBitString, atoBitPattern,
  1111. printon, ostream <<)') are also as in BitSets, except that no virtual
  1112. bit is used, and an 'X' in a BitPattern means that the pattern bit is
  1113. masked out.
  1114.  
  1115.    The following features are unique to BitStrings.
  1116.  
  1117.    Assume declarations of BitString a = atoBitString("01010110") and b =
  1118. atoBitSTring("1101").
  1119.  
  1120. `a = b + c;'
  1121.      Sets a to the concatenation of b and c;
  1122.  
  1123. `a = b + 0; a = b + 1;'
  1124.      sets a to b, appended with a zero (one).
  1125.  
  1126. `a += b;'
  1127.      appends b to a;
  1128.  
  1129. `a += 0; a += 1;'
  1130.      appends a zero (one) to a.
  1131.  
  1132. `a << 2; a <<= 2'
  1133.      return a with 2 zeros prepended, setting a to 0001010110. (Note
  1134.      the necessary confusion of << and >> operators. For consistency
  1135.      with the integer versions, << shifts low bits to high, even though
  1136.      they are printed low bits first.)
  1137.  
  1138. `a >> 3; a >>= 3'
  1139.      return a with the first 3 bits deleted, setting a to 10110.
  1140.  
  1141. `a.left_trim(0)'
  1142.      deletes all 0 bits on the left of a, setting a to 1010110.
  1143.  
  1144. `a.right_trim(0)'
  1145.      deletes all trailing 0 bits of a, setting a to 0101011.
  1146.  
  1147. `cat(x, y, z)'
  1148.      A faster way to say z = x + y.
  1149.  
  1150. `diff(x, y, z)'
  1151.      A faster way to say z = x - y.
  1152.  
  1153. `and(x, y, z)'
  1154.      A faster way to say z = x & y.
  1155.  
  1156. `or(x, y, z)'
  1157.      A faster way to say z = x | y.
  1158.  
  1159. `xor(x, y, z)'
  1160.      A faster way to say z = x ^ y.
  1161.  
  1162. `lshift(x, y, z)'
  1163.      A faster way to say z = x << y.
  1164.  
  1165. `rshift(x, y, z)'
  1166.      A faster way to say z = x >> y.
  1167.  
  1168. `complement(x, z)'
  1169.      A faster way to say z = ~x.
  1170.  
  1172. File: libg++.info,  Node: Random,  Next: Data,  Prev: Bit,  Up: Top
  1173.  
  1174. Random Number Generators and related classes
  1175. ********************************************
  1176.  
  1177.    The two classes `RNG' and `Random' are used together to generate a
  1178. variety of random number distributions.  A distinction must be made
  1179. between *random number generators*, implemented by class `RNG', and
  1180. *random number distributions*.  A random number generator produces a
  1181. series of randomly ordered bits.  These bits can be used directly, or
  1182. cast to other representations, such as a floating point value.  A
  1183. random number generator should produce a *uniform* distribution.  A
  1184. random number distribution, on the other hand, uses the randomly
  1185. generated bits of a generator to produce numbers from a distribution
  1186. with specific properties.  Each instance of `Random' uses an instance
  1187. of class `RNG' to provide the raw, uniform distribution used to produce
  1188. the specific distribution.  Several instances of `Random' classes can
  1189. share the same instance of `RNG', or each instance can use its own copy.
  1190.  
  1191. RNG
  1192. ===
  1193.  
  1194.    Random distributions are constructed from members of class `RNG',
  1195. the actual random number generators.  The `RNG' class contains no data;
  1196. it only serves to define the interface to random number generators.
  1197. The `RNG::asLong' member returns an unsigned long (typically 32 bits)
  1198. of random bits.  Applications that require a number of random bits can
  1199. use this directly.  More often, these random bits are transformed to a
  1200. uniform random number:
  1201.  
  1202.          //
  1203.          // Return random bits converted to either a float or a double
  1204.          //
  1205.          float asFloat();
  1206.          double asDouble();
  1207.      };
  1208.  
  1209. using either `asFloat' or `asDouble'.  It is intended that `asFloat'
  1210. and `asDouble' return differing precisions; typically, `asDouble' will
  1211. draw two random longwords and transform them into a legal `double',
  1212. while `asFloat' will draw a single longword and transform it into a
  1213. legal `float'.  These members are used by subclasses of the `Random'
  1214. class to implement a variety of random number distributions.
  1215.  
  1216. ACG
  1217. ===
  1218.  
  1219.    Class `ACG' is a variant of a Linear Congruential Generator
  1220. (Algorithm M) described in Knuth, *Art of Computer Programming, Vol
  1221. III*.  This result is permuted with a Fibonacci Additive Congruential
  1222. Generator to get good independence between samples.  This is a very high
  1223. quality random number generator, although it requires a fair amount of
  1224. memory for each instance of the generator.
  1225.  
  1226.    The `ACG::ACG' constructor takes two parameters: the seed and the
  1227. size.  The seed is any number to be used as an initial seed. The
  1228. performance of the generator depends on having a distribution of bits
  1229. through the seed.  If you choose a number in the range of 0 to 31, a
  1230. seed with more bits is chosen. Other values are deterministically
  1231. modified to give a better distribution of bits.  This provides a good
  1232. random number generator while still allowing a sequence to be repeated
  1233. given the same initial seed.
  1234.  
  1235.    The `size' parameter determines the size of two tables used in the
  1236. generator. The first table is used in the Additive Generator; see the
  1237. algorithm in Knuth for more information. In general, this table is
  1238. `size' longwords long. The default value, used in the algorithm in
  1239. Knuth, gives a table of 220 bytes. The table size affects the period of
  1240. the generators; smaller values give shorter periods and larger tables
  1241. give longer periods. The smallest table size is 7 longwords, and the
  1242. longest is 98 longwords. The `size' parameter also determines the size
  1243. of the table used for the Linear Congruential Generator. This value is
  1244. chosen implicitly based on the size of the Additive Congruential
  1245. Generator table. It is two powers of two larger than the power of two
  1246. that is larger than `size'.  For example, if `size' is 7, the ACG table
  1247. is 7 longwords and the LCG table is 128 longwords. Thus, the default
  1248. size (55) requires 55 + 256 longwords, or 1244 bytes. The largest table
  1249. requires 2440 bytes and the smallest table requires 100 bytes.
  1250. Applications that require a large number of generators or applications
  1251. that aren't so fussy about the quality of the generator may elect to
  1252. use the `MLCG' generator.
  1253.  
  1254. MLCG
  1255. ====
  1256.  
  1257.    The `MLCG' class implements a *Multiplicative Linear Congruential
  1258. Generator*. In particular, it is an implementation of the double MLCG
  1259. described in *"Efficient and Portable Combined Random Number
  1260. Generators"* by Pierre L'Ecuyer, appearing in *Communications of the
  1261. ACM, Vol. 31. No. 6*. This generator has a fairly long period, and has
  1262. been statistically analyzed to show that it gives good inter-sample
  1263. independence.
  1264.  
  1265.    The `MLCG::MLCG' constructor has two parameters, both of which are
  1266. seeds for the generator. As in the `MLCG' generator, both seeds are
  1267. modified to give a "better" distribution of seed digits. Thus, you can
  1268. safely use values such as `0' or `1' for the seeds. The `MLCG'
  1269. generator used much less state than the `ACG' generator; only two
  1270. longwords (8 bytes) are needed for each generator.
  1271.  
  1272. Random
  1273. ======
  1274.  
  1275.    A random number generator may be declared by first declaring a `RNG'
  1276. and then a `Random'. For example, `ACG gen(10, 20); NegativeExpntl rnd
  1277. (1.0, &gen);' declares an additive congruential generator with seed 10
  1278. and table size 20, that is used to generate exponentially distributed
  1279. values with mean of 1.0.
  1280.  
  1281.    The virtual member `Random::operator()' is the common way of
  1282. extracting a random number from a particular distribution.  The base
  1283. class, `Random' does not implement `operator()'. This is performed by
  1284. each of the subclasses. Thus, given the above declaration of `rnd', new
  1285. random values may be obtained via, for example, `double next_exp_rand =
  1286. rnd();' Currently, the following subclasses are provided.
  1287.  
  1288. Binomial
  1289. ========
  1290.  
  1291.    The binomial distribution models successfully drawing items from a
  1292. pool.  The first parameter to the constructor, `n', is the number of
  1293. items in the pool, and the second parameter, `u', is the probability of
  1294. each item being successfully drawn.  The member `asDouble' returns the
  1295. number of samples drawn from the pool.  Although it is not checked, it
  1296. is assumed that `n>0' and `0 <= u <= 1'.  The remaining members allow
  1297. you to read and set the parameters.
  1298.  
  1299. Erlang
  1300. ======
  1301.  
  1302.    The `Erlang' class implements an Erlang distribution with mean
  1303. `mean' and variance `variance'.
  1304.  
  1305. Geometric
  1306. =========
  1307.  
  1308.    The `Geometric' class implements a discrete geometric distribution.
  1309. The first parameter to the constructor, `mean', is the mean of the
  1310. distribution.  Although it is not checked, it is assumed that `0 <=
  1311. mean <= 1'.  `Geometric()' returns the number of uniform random samples
  1312. that were drawn before the sample was larger than `mean'.  This
  1313. quantity is always greater than zero.
  1314.  
  1315. HyperGeometric
  1316. ==============
  1317.  
  1318.    The `HyperGeometric' class implements the hypergeometric
  1319. distribution.  The first parameter to the constructor, `mean', is the
  1320. mean and the second, `variance', is the variance.  The remaining
  1321. members allow you to inspect and change the mean and variance.
  1322.  
  1323. NegativeExpntl
  1324. ==============
  1325.  
  1326.    The `NegativeExpntl' class implements the negative exponential
  1327. distribution.  The first parameter to the constructor is the mean.  The
  1328. remaining members allow you to inspect and change the mean.
  1329.  
  1330. Normal
  1331. ======
  1332.  
  1333.    The `Normal'class implements the normal distribution.  The first
  1334. parameter to the constructor, `mean', is the mean and the second,
  1335. `variance', is the variance.  The remaining members allow you to
  1336. inspect and change the mean and variance.  The `LogNormal' class is a
  1337. subclass of `Normal'.
  1338.  
  1339. LogNormal
  1340. =========
  1341.  
  1342.    The `LogNormal'class implements the logarithmic normal distribution.
  1343. The first parameter to the constructor, `mean', is the mean and the
  1344. second, `variance', is the variance.  The remaining members allow you
  1345. to inspect and change the mean and variance.  The `LogNormal' class is
  1346. a subclass of `Normal'.
  1347.  
  1348. Poisson
  1349. =======
  1350.  
  1351.    The `Poisson' class implements the poisson distribution.  The first
  1352. parameter to the constructor is the mean.  The remaining members allow
  1353. you to inspect and change the mean.
  1354.  
  1355. DiscreteUniform
  1356. ===============
  1357.  
  1358.    The `DiscreteUniform' class implements a uniform random variable over
  1359. the closed interval ranging from `[low..high]'.  The first parameter to
  1360. the constructor is `low', and the second is `high', although the order
  1361. of these may be reversed.  The remaining members allow you to inspect
  1362. and change `low' and `high'.
  1363.  
  1364. Uniform
  1365. =======
  1366.  
  1367.    The `Uniform' class implements a uniform random variable over the
  1368. open interval ranging from `[low..high)'.  The first parameter to the
  1369. constructor is `low', and the second is `high', although the order of
  1370. these may be reversed.  The remaining members allow you to inspect and
  1371. change `low' and `high'.
  1372.  
  1373. Weibull
  1374. =======
  1375.  
  1376.    The `Weibull' class implements a weibull distribution with
  1377. parameters `alpha' and `beta'.  The first parameter to the class
  1378. constructor is `alpha', and the second parameter is `beta'.  The
  1379. remaining members allow you to inspect and change `alpha' and `beta'.
  1380.  
  1381. RandomInteger
  1382. =============
  1383.  
  1384.    The `RandomInteger' class is *not* a subclass of Random, but a
  1385. stand-alone integer-oriented class that is dependent on the RNG
  1386. classes. RandomInteger returns random integers uniformly from the
  1387. closed interval `[low..high]'.  The first parameter to the constructor
  1388. is `low', and the second is `high', although both are optional.  The
  1389. last argument is always a generator.  Additional members allow you to
  1390. inspect and change `low' and `high'.  Random integers are generated
  1391. using `asInt()' or `asLong()'.  Operator syntax (`()') is also
  1392. available as a shorthand for `asLong()'.  Because `RandomInteger' is
  1393. often used in simulations for which uniform random integers are desired
  1394. over a variety of ranges, `asLong()' and `asInt' have `high' as an
  1395. optional argument.  Using this optional argument produces a single
  1396. value from the new range, but does not change the default range.
  1397.  
  1398.